Skip to main content

Security Architecture

This page is the consolidated security reference for Aspects. It describes how Aspects execute, where the trust boundaries are, who owns each layer, and what defenses the Forge CLI applies at every step. It complements the per-template details in Web Technical Reference — Security model and the per-control matrix in Template Families — Built-in Security Controls.

Audience: FI AppSec / security architects reviewing an Aspect deployment, partner integrators authoring custom snippets, Candescent platform engineers.

Execution Model​

┌──────────────────────────────────────────────────────────────┐
│  FI Digital Banking Application (Parent Window)              │
│                                                              │
│   ┌─────────────────────────────────────────────────────┐    │
│   │  Static Aspect Loader (immutable, FI-hosted)        │    │
│   │  • Generated by  forge aspect submit               │    │
│   │  • Reviewed + merged into FI's extension repo       │    │
│   │  • Served from FI's CDN                             │    │
│   │  • Inlines validators (XSS, URL, session, message)  │    │
│   └────────────────────┬────────────────────────────────┘    │
│                        │                                     │
│                        ▼                                     │
│   ┌─────────────────────────────────────────────────────┐    │
│   │  Runtime Execution Context                          │    │
│   │  • Parent window DOM (default)                      │    │
│   │  • Sandboxed iframe (hidden-iframe-sso)             │    │
│   │  • WebView (mobile templates)                       │    │
│   └────────────────────┬────────────────────────────────┘    │
│                        │                                     │
└────────────────────────┼─────────────────────────────────────┘
                         │
                         ▼
            ┌──────────────────────────────┐
            │  Optional runtime services    │
            │  • OIDC token endpoint        │
            │  • Vendor SDK CDN             │
            │  • SSO / federation IdP       │
            │  • Mobile JSBridge            │
            └──────────────────────────────┘

Every Aspect is a static, FI-hosted JavaScript file. It does not execute Candescent-hosted code at runtime — the Forge CLI only generates the file at authoring time. After review, the file lives in the FI's own extension repository and is served from the FI's CDN under the FI's CSP.

Trust Zones​

Aspects operate across three trust zones with strictly enforced boundaries between them:

┌──────────────────────────────────────────────────────────────┐
│ Zone 1: FI-Controlled                                        │
│ • Static loader script (after FI review + merge)             │
│ • dbk API surface (sessionInfo, loadScript, isWebview)       │
│ • User session cookies, host CSP, CDN delivery               │
└──────────────────────┬───────────────────────────────────────┘
                       │ Validated via:
                       │   - Aspect submission review
                       │   - SRI on vendor scripts
                       │   - postMessage origin allowlist
                       │   - Session schema validation
                       ▼
┌──────────────────────────────────────────────────────────────┐
│ Zone 2: Vendor Runtime (conditional trust)                   │
│ • Vendor SDKs loaded with SRI                                │
│ • SSO endpoints inside sandboxed iframes                     │
│ • Mobile vendor SDKs loaded after JSBridge token             │
└──────────────────────┬───────────────────────────────────────┘
                       │ No direct parent-DOM access:
                       │   - Iframe sandbox (sso)
                       │   - postMessage schema validation
                       │   - bubbles:false / composed:false
                       ▼
┌──────────────────────────────────────────────────────────────┐
│ Zone 3: External Telemetry / Analytics (minimal trust)       │
│ • One-way fetches over HTTPS                                 │
│ • No PII without explicit consent                            │
│ • Subject to FI's CSP `connect-src`                          │
└──────────────────────────────────────────────────────────────┘

Party Responsibilities​

LayerOwnerWhat they controlWhat the Forge CLI guarantees on their behalf
Static loader hostingFICDN, cache, CSP headersGenerated file is byte-stable across deployments; no dynamic Candescent calls at runtime
dbk API surfaceFIsessionInfo payload contents, JSBridge implementation, presence of loadScriptAspects always type-check dbk and degrade gracefully when methods are absent
Aspect template logicCandescent (CLI)Inlined validators, escape helpers, fetch wrappers, sandbox attributesEvery emitted snippet is unit-tested for the controls listed in Template Families — Built-in Security Controls
Vendor SDKsVendor (third party)SDK source, CDNLoaded with optional SRI (--integrity); FI sees a clear onerror diagnostic when integrity fails
OIDC / SSO endpointsFI or federated IdPBackend cert, token signingAspects never see access tokens — only authorization codes pass through the front-end
Telemetry / logsFIWhat the host shell does with console.* outputTemplates emit [cdx-aspect:<correlation-id>] prefixes for cross-trust-boundary templates so the FI can attribute log lines to specific deployments

Coverage Against the Questionnaire​

The full Aspect Architecture, Security & Compatibility Questionnaire is reproduced verbatim in Security Questionnaire (Vendor Response), along with:

  • A coverage matrix mapping each questionnaire section onto every template (✓ CLI-enforced / ◯ FI-configured / — n/a).
  • Per-template completed responses for the three high-leverage templates (oidc-snippet, hidden-iframe-sso, mobile-vendor-chat-jsbridge).
  • Family-grouped summaries for the remaining 12 templates.

Use the questionnaire page to answer specific questions during AppSec review; use this page for the trust-zone diagram + party-responsibility framing.

Out of Scope (for the current release)​

The following are deliberately deferred and must be implemented by the FI or coordinated with Candescent before deployment if the FI's risk model requires them:

  • Shadow DOM CSS isolation. Parent-page styles can affect Aspect UI. FIs that need bullet-proof isolation should review the emitted snippet and either accept the styling risk or coordinate a Shadow-DOM redesign with Candescent.
  • HMAC signature verification on SSO signature. The Forge CLI type-checks the field; FIs must verify cryptographically against their signing key.
  • Centralized telemetry pipeline. Correlation IDs land in console.*; there is no automatic forwarding to a Candescent telemetry endpoint.
  • Vendor-supplied inline scripts. vendor-script-loader and friends do not introspect what the vendor SDK does after it loads. FIs are responsible for vendor security review.

Verifying the Defense Layers in a Generated Snippet​

After generating an Aspect, you can confirm the layers are present with simple grep checks:

Bash
forge aspect preview --template oidc-snippet --client-id my-app --fi-domain acmebank --no-playground

# In the saved file:
grep -c '__cdxValidateSession\|__cdxEsc\|__cdxValidateHttpUrl' ./aspects/oidc-snippet.js
grep -c 'function __cdxFetch'                                  ./aspects/oidc-snippet.js
grep -c '\[cdx-aspect:'                                        ./aspects/oidc-snippet.js
grep -c 'onclick=\|onerror=\|onload='                          ./aspects/oidc-snippet.js   # expect 0

For an FI-side audit, see the Deployment Security Checklist — the expected outputs for each grep are listed alongside the controls.

Next Steps​